- Overview of the Gray Council MacApp adapter classes.
- Instructions for using the MacApp adapter classes.
Instructions for building the Gray Council MacApp sample/test application.
1. Open the .π file of choice (68K or PowerPC) with CodeWarrior.
2. Where necessary, change the access paths listed below, and change them so that they point to where you keep the corresponding items on your system. Your MacApp and RIncludes folders may not be located or named the way mine are, so alter these as necessary:
a. If your MacApp root folder is sibling with the GrayCouncil root folder and is named "MacApp 3.3", these access paths should be OK the way they are; if not, point them to the right place:
b. If you have installed the CodeWarrior-supplied MPW into the CW9 Gold folder, this access path should be OK the way it is; if not, point it to the right place:
3. Select the Run command to compile, link, and launch the application.
Overview of the Gray Council MacApp adapter classes.
AGAPushButtonMA
Replacement subclass of TButton. Implements the AGA pushbutton by instantiating a core AGAPushButton object.
Recommended dimensions: 20x64 or 20x80, or wider to fit longer title. Add 8x8 for default buttons.
AGACheckBoxMA
Replacement subclass of TCheckBox. Implements the AGA check box by instantiating a core AGACheckBox object. To use the "mixed-state" capability, call mAGAObject->SetState/GetState.
Minimum dimensions: 12xY.
AGARadioButtonMA
Replacement subclass of TRadioButton. Implements the AGA radio button by instantiating a core AGARadioButton object. To use the "mixed-state" capability, call mAGAObject->SetState/GetState.
Minimum dimensions: 12xY.
AGAIconPushButtonMA
Replacement subclass of AGAPushButtonMA (TButton), acts like a regular springloaded pushbutton, but with icon button appearance. Implements the AGA icon button by instantiating a core AGAIconPushButton object. The fUserArea should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAIconCheckBoxMA
Replacement subclass of AGACheckBoxMA (TCheckBox), acts like a regular self-toggling check box, but with icon button appearance. Implements the AGA check box by instantiating a core AGAIconCheckBox object. The fUserArea should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAIconRadioButtonMA
Replacement subclass of AGARadioButtonMA (TRadioButton), acts like a regular radio button that can be grouped in a TCluster for mutual exclusivity, but with icon button appearance. The fUserArea should contain the icon family resource ID.
Recommended dimensions: 22x22 for small icons, 40x40 for large icons.
AGAScrollBarMA
Replacement subclass of TScrollBar. Implements the AGA scroll bar by instantiating a core AGAScrollBar. By default, live scrolling is on and proportional indicator is off. You can change these defaults globally via SetGrayCouncilDefault or per object via SetAttributes.
Recommended dimensions: Xx16 or 16xY.
AGAScrollerScrollBarMA
Replacement subclass of TScrollerScrollBar. Implements the AGA scroll bar by instantiating a core AGAScrollBar. By default, live scrolling is on and proportional indicator is off. You can change these defaults globally via SetGrayCouncilDefault or per object via SetAttributes.
Recommended dimensions: Xx16 or 16xY.
AGASliderMA
A subclass of TControl. Implements AGA slider by instantiating a core AGASlider. If the fUserArea contains a valid STR# resource ID, the slider will be labeled/pointy, the slider labels are read from that resource, the slider range is initialized to match the number of labels. Otherwise, the slider will be unlabeled/rectangular.
Minimum dimensions: Xx17 or 17xY.
AGABackgroundAdornerMA
A subclass of TAdorner. To get a gray window background, attach this adorner to the window in front of the Draw adorner. This adorner is for a modeless window, such as a document window.
AGAModalBackgroundAdornerMA
A subclass of TAdorner. To get a gray dialog background, attach this adorner to the dialog in front of the Draw adorner. This adorner is for a modal window, such as a modal dialog box or movable modal dialog window.
AGAWhiteBackgroundAdornerMA
A subclass of TAdorner. To get a white subview background against a gray window background, attach this adorner to the subview in front of the Draw adorner. This adorner will be common for editable text views and list views, usually used with a AGABorderFrameAdornerMA.
AGABorderFrameAdornerMA
A subclass of TAdorner. To get a "3D" sunken subview frame, attach this adorner to the subview behind the Draw adorner. This adorner will be common for editable text views and list views, usually used with a AGAWhiteBackgroundAdornerMA.
AGAPopupMA
Replacement subclass of TPopup. Implements the AGA popup menu by instantiating a core AGAPopupMenu.
Recommended dimensions: 20xY. Supports a horizontal size determiner of variable or fixed width; fixed width means that the view is always drawn to fill the width of the view, while variable means it shrinks to fit the actual width.
AGAStaticTextMA
Replacement subclass of TStaticText. Implements static text that draws disabled in "real" gray (not qd.gray erase patBic), and erases to gray on a non-white background, by instantiating a core AGAStaticText. You can just use TStaticText if you do not change the text while the window is visible, but if you update the text while the window is open, use AGAStaticTextMA to avoid a white hole in the window; otherwise you'll need to attach a gray background adorner to the view...
Recommended dimensions: n/a; depends on font size.
AGALittleArrowsMA
A subclass of TControl. Implements AGA little arrows by instantiating a core AGALittleArrows. If the fUserArea contains the subview ID of a TNumberText subview in the same window, the little arrows will automatically increment/decrement the value of the number field.
Minimum dimensions: 23x13.
AGADisclosureTriangleMA
A subclass of TControl. Implements AGA disclosure triangle by instantiating a core AGADisclosureTriangle.
Minimum dimensions: 10x10.
AGAProgressIndicatorMA
A subclass of TControl. Implements AGA determinate and indeterminate progress indicators by instantiating a core AGAProgress indicator. To set the indicator's min/max range, call mAGAObject->SetRange. If you set min=max, you get an indeterminate indicator. Call mAGAObject->SetValue or Increment to prod a determinate indicator; call mAGAObject->Animate to rotate an indeterminate indicator once.
Required dimensions: Xx14.
AGASeparatorMA
A subclass of TView. Implements AGA separator by instantiating a core AGASeparator. The larger dimension (h/v) is the direction that the separator is drawn.
Minimum dimensions: Xx2 or 2xY.
AGATargetBorderViewMA
Replacement subclass of TTargetBorderView. Implements AGA keyboard focus frame by changing the color and shape of the target border.
Recommended dimensions: n/a; fit to contain subview.
AGATargetBorderFrameViewMA
Replacement subclass of AGATargetBorderViewMA (TTargetBorderView). In addition to the AGA keyboard focus indicator, draws a "3D" sunken subview frame exactly like the AGABorderFrameAdornerMA. This is so that you don't have to also attach an AGABorderFrameAdornerMA to the subview.
Recommended dimensions: n/a; fit to contain subview.
AGAGroupBoxMA
Replacement subclass of TCluster. Implements AGA primary group box by instantiating a core AGAGroupBox set for "primary" look. Differs from TCluster in that if it has no title it still draws, so if you want a non-visible cluster, just use a TCluster. If the fUserArea contains the subview ID of a sibling subview, that other view's width will be used to determine the "title gap" that is left blank for the other view to occupy.
Recommended dimensions: n/a; fit to contain subviews. If you use a sibling view for the title gap, you'll need to locate it at the correct location to sit in the title gap. As an example, if you use a 16xY check box for the group box title, the check box view should be located at left+14, top-9 relative to the group box. To conform precisely to the AGA guidelines, the title's baseline should match the group box top, and there should be 3 blank pixels on each side of the title.
AGASecondaryGroupBoxMA
Replacement subclass of AGAGroupBoxMA (TCluster). Implements AGA secondary group box by instantiating a core AGAGroupBox set for "secondary" look.
Recommended dimensions: same as for AGAGroupBoxMA.
Instructions for using the Gray Council MacApp adapter classes.
1. Adding the Gray Council files to your project.
Your project needs to add two Gray Council files:
- GrayCouncil.cpp (the core classes)
- GrayCouncilMA.cpp (the MacApp adapter classes)
You also need to have the path to the corresponding header files in your Access Paths. One path that is usually missing from the CodeWarrior project stationery, and which is used by the GrayCouncil code, is:
{Compiler ƒ}:MacOS Support:Headers:STL Headers:
The Gray Council .cpp and .h files don't rely on any particular folder hierarchy, so you can organize them however you want. (However, the provided sample app has certain relative file path assumptions, as discussed earlier.)
If it's not already in the project, you will need to add the PLStringFuncs glue, which is used by the core Gray Council code.
The 68K version is ":MacOS Support:Libraries:MacOS 68K:MacOS Files:PLStringFuncs.glue.lib"
The PPC version is ":MacOS Support:Libraries:MacOS PPC:PLStringFuncs Glue:PLStringFuncsPPC.lib"
2. Initializing.
You must call InitGrayCouncilMA() after MacApp has initialized the toolbox but before you instantiate any Gray Council objects. You should FailOSErr() on the result. This function call registers the MacApp adapter view classes and then calls InitGrayCouncil.
3. Specifying the view class.
(Note: feel free to open the file MyApplication.rsrc with AdLib to see the details of the view resources used for the sample app.)
For resource-based views, you just need to set the class name of the subview in the resource. For most views, this is all you need to do; in some of the fancier classes, you will also want to set attributes at runtime. Some classes also support use of the "user area" field to specify attributes. You can also statically instantiate views at runtime; each class has a MacApp-style "I" method that you must call to initialize the object.
- For an AdLib or ViewEdit resource file, simply go to the subview's class name field and type in the new class name. Make sure you use the MacApp adapter class name (ending in "MA"), not the core Gray Council class name.
- For a derezzed View in a .r file, you type the Gray Council MacApp adapter class name between the "" double quotes near the top of the subview's definition. For example, where you previously had:
ViewSignatureAndClassname {
'butn',
206,
"",
...change it to:
ViewSignatureAndClassname {
'butn',
206,
"AGAPushButtonMA",
4. Setting the fUserArea.
The following summarizes how the "user area" or "user data" field of a subview in a resource specifies additional information for certain classes (zero means to ignore it). This information is also listed in the class overviews above.
AGAIconPushButtonMA::fUserArea specifies the resource ID of an icon family for the icon button.
AGAIconCheckBoxMA::fUserArea specifies the resource ID of an icon family for the icon button.
AGAIconRadioButtonMA::fUserArea specifies the resource ID of an icon family for the icon button.
AGASliderMA::fUserArea specifies the STR# resource ID of the slider labels.
AGALittleArrowsMA::fUserArea specifies the IDType of a TNumberText subview in the same window to be automatically linked to the arrows.
AGAGroupBoxMA::fUserArea specifies the IDType of a sibling subview whose width will be used to determine the "title gap" of the group box.
5. Changing attributes at runtime.
Once you have a Gray Council view instantiated, either from a view resource or statically, you will want to do something with it! For the MacApp replacement subclasses, you can probably just plug them in; all standard functions like TCheckBox::Toggle and TPopup::GetCurrentItem will continue to work for the replacement subclasses. The only thing you need to avoid (and you should already be avoiding this) is for TCtlMgr subclasses, don't set or get the control manager value directly. You can continue to use the Set/GetLongMax functions, and you'll still be OK.
For some classes, there is no MacApp equivalent, so you'll need to call the view's mAGAObject-> functions directly. (This is why the mAGAObject data member is made public: so you can just call though without going through an accessor.) There is really only one thing to be careful of: focusing. Because the core AGA classes are designed to be ultra lightweight, they do not store a GrafPtr. They assume that the port is set up by the caller. So you must make sure that the view is focused before you explicitly call an AGAObject function that will cause drawing. The MacApp adapter classes already do this by calling this->Focus() where necessary.
